focus-lock

What is focus-lock?

The focus-lock npm package is designed to trap focus within a specified DOM element, typically used in modal dialogs, popups, and similar components to enhance accessibility and user experience. It prevents users from tabbing out of the focused area into other parts of the webpage, ensuring that keyboard and screen reader users have a confined, manageable interaction space.

What are focus-lock's main functionalities?

Focus trapping within a DOM element

This feature allows developers to create a focus trap around a specified DOM element. When activated, all tab and shift+tab keystrokes are confined within the element, enhancing accessibility for modal dialogs.

import { FocusTrap } from 'focus-lock';

const focusTrap = new FocusTrap('#myDialog');
focusTrap.activate();
// When done
focusTrap.deactivate();

Auto focusing on the first focusable element

Automatically focuses the first focusable element within the component when activated. This is useful for ensuring that users start interacting with the most relevant part of a newly opened UI component.

import { AutoFocusInside } from 'focus-lock';

<AutoFocusInside>
  <input type='text' />
  <button>Click me</button>
</AutoFocusInside>

Return focus to initial element on deactivation

When the focus lock is deactivated, focus can be programmatically moved back to the initially focused element before the focus lock was activated, maintaining a logical flow of interaction.

import { MoveFocusInside } from 'focus-lock';

const initialFocus = document.getElementById('initialFocus');
// After deactivating the focus lock
MoveFocusInside(initialFocus);

Other packages similar to focus-lock

react-focus-lock

A React-specific implementation of focus trapping. It provides similar functionalities as focus-lock but is tailored for React applications, making it easier to integrate with React component lifecycle.

a11y-dialog

This package provides a lightweight yet robust solution for creating accessible dialog windows. While it includes focus trapping as part of its functionality, it also manages aria attributes and supports multiple dialog instances, offering a broader scope compared to focus-lock.

README

focus-lock

It is a trap! We got your focus and will not let him out!

Consumers

This is a base package for:

• react-focus-lock
• vue-focus-lock
• dom-focus-lock

Provides a low level API, to be used by final realization. Usually everything can be solved in 3 lines

import moveFocusInside, { focusInside } from 'focus-lock';

if (topNode && !focusInside(topNode)) {
  moveFocusInside(topNode, lastActiveFocus);
}

Additional API

Programmatic focus management

import { focusNextElement, focusPrevElement } from 'focus-lock';
focusNextElement(sourceElement, {
  scope: theBoundingDOMNode,
}); // -> next tabbable element

WHY?

From MDN Article about accessible dialogs:

• The dialog must be properly labeled
• Keyboard focus must be managed correctly

This one is about managing the focus.

I'v got a good article about focus management, dialogs and WAI-ARIA.

Declarative control

Focus-lock provides not only API to be called by some other scripts, but also a way one can leave instructions inside HTML markup to amend focus behavior in a desired way.

These are data-attributes one can add on the elements:

• control
  • data-focus-lock to create a focus group (scattered focus)
  • data-focus-lock-disabled marks such group as disabled and removes from the list
  • data-no-focus-lock focus-lock will ignore focus inside marked area
• autofocus
  • data-autofocus will autofocus marked element on activation. Require control delegation to focus-lock
  • data-autofocus-inside focus-lock will try to autofocus elements within selected area
  • data-no-autofocus focus-lock will not autofocus any node within marked area

These markers are available as import * as markers from 'focus-lock/constants'

Focus fighting

It is possible, that more that one "focus management system" is present on the site. For example, you are using FocusLock for your content, and also using some Modal dialog, with FocusTrap inside.

Both system will try to do their best, and move focus into their managed areas. Stack overflow. Both are dead.

Focus Lock(React-Focus-Lock, Vue-Focus-Lock and so on) implements anti-fighting protection - once the battle is detected focus-lock will surrender(as long there is no way to win this fight).

You may also land a peace by special data attribute - data-no-focus-lock(constants.FOCUS_ALLOW). It will remove focus management from all nested elements, letting you open modals, forms, or use any third party component safely. Focus lock will just do nothing, while focus is on the marked elements.

API

default(topNode, lastNode) (aka setFocus), moves focus inside topNode, keeping in mind that last focus inside was - lastNode

Licence

MIT

Changelog

0.11.6 (2023-02-16)

Bug Fixes

• secure access to cross-origin iframes, fixes #45 (860e283)